C/C++ Users Group Library 1996 July

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 436_01 / incon.doc < prev next >

Wrap

Text File | 1994-10-07 | 64.5 KB | 1,783 lines

INCON.DOC Documentation for INCON (INput CONtrol) Version 3.1 Richard Zigler PO Box 152 McBain, MI 49657-0152 Contents Copyright Notice and Disclaimer.................................2 Introduction....................................................3 Basic Operation..............................................3 INCON Parameters................................................3 BufOff.......................................................4 BufSeg.......................................................4 KeyOff.......................................................4 KeySeg.......................................................4 Flags........................................................5 Debug.....................................................5 Type......................................................5 Justify...................................................6 Strip.....................................................6 Message...................................................6 Sign......................................................7 Display...................................................7 Confirm...................................................7 Delimit...................................................7 xKeys.....................................................7 Scroll....................................................8 Hide......................................................8 Template..................................................8 Width........................................................9 Prec........................................................10 Visible.....................................................10 Attr........................................................10 Fill........................................................10 Pad.........................................................10 Setting up the Message Block and Calling INCON.................11 Extended-Key Trapping..........................................11 Special Exit Keys...........................................12 Setting Up and Editing Input Fields............................13 Input Templates.............................................14 Floating-point Fields.......................................16 Scrolling Fields............................................18 Return Codes...................................................18 Run-Time Errors................................................20 Error Trapping..............................................21 Figures and Tables.............................................23 Figure 1. INCON Message Block..............................23 Figure 2. INCON Flags......................................23 Figure 3. The INCON Interface..............................24 Figure 4. The INCON Stat Box...............................25 Table 1. INCON's Handling of [Numpad +] and [Numpad -]....25 Table 2. INCON Edit Keys..................................26 INCON.DOC 1 Copyright Notice and Disclaimer For purposes of this Notice and Disclaimer, "INCON" means the INCON source and header files, this document, and any other software and documentation supplied as an adjunct to INCON, all of which are Copyright (c) 1993-94, by Richard Zigler. INCON may be freely copied and distributed but not modified or sold for profit, either as a discrete product or as part of a commercial product, without written consent of the author, except that software libraries may charge a nominal fee for a disk containing INCON. You undertake to use INCON at your own risk. The author assumes no liability for damages resulting from your use of INCON and makes no warranty of any kind with regard to INCON and its use. Address questions, suggestions, or comments to: Richard Zigler PO Box 152 McBain, MI 49657-0152 INCON.DOC 2 Introduction INCON is an MS-DOS input management library that helps you build sophisticated data input screens. INCON gives you control over the placement and appearance of input fields, and the type and amount of data that each will accept. Input fields may be alphanumeric, uppercase, integer, or floating-point. You may pass an ASCIIZ string to INCON and specify that it be treated as default input or as an input template, or both. Templates may be alpha, numeric, or mixed. You may specify that fields scroll, that they be delimited, that user input be hidden, and that input be returned to your program left- or right-justified or centered in a field whose width and "pad" character you select. A number of reserved edit keys give users of your programs extensive input editing capabilities. Several assembly language string-handling routines are available as part of INCON and in a separate object file. Basic Operation The basic operation of the program is as follows: 1. The calling routine defines a block of parameters, among which is a far pointer to an i/o buffer. 2. At entry, INCON copies any string in the i/o buffer to an internal work buffer and may then display it as default input or use it to construct an input template, or both. 3. User keyboard entries are examined. INCON acts upon its reserved keys immediately. It returns extended-key codes that it finds in a list provided by the calling routine and cancels the input operation. It displays and saves in the work buffer all entries that are appropriate to the field type; it discards all others. 4. If the operation succeeds, INCON copies user input to the i/o buffer, overwriting its previous contents. If it fails or is canceled, INCON discards any user input it has so far gathered. 5. INCON returns a code to the calling routine that indicates input status or whether the user has made a special request. INCON Parameters Parameters occupy a "message block," to which you pass a far pointer in the call to INCON. The message block is defined as a C data object called a union, which allows data of different types to share the same memory area, or, to look at it another way, data in a INCON.DOC 3 given memory area to be addressed as different types. The message block is defined as both an array of unsigned integers and a structure comprising data of various types. That makes it possible for languages that don't offer structured-data capabilities or bit-level operators to access the message block as a simple array, using logical and arithmetic operators. Declarations and definitions for the message block are in the header file INDEFS.H. The message block is arranged as in Figure 1. Parameters are unsigned, limiting the range of byte-size quantities to 0 to 255. Note that you don't pass the input field screen coordinates. One of the first things that INCON does is determine for itself the absolute coordinates of the current cursor position. You may use INCON to set up input fields in programs that employ text windows, without worrying about coordinate translation; just put the cursor where you want the field to appear before issuing the call. You must ensure, however, that the field does not extend beyond the boundaries of its host window. BufOff Offset address of the i/o buffer. Prior to calling INCON, you may load the buffer with a null-terminated string and, depending on the condition of the Template flag (see below), INCON treats the string either as default input or as an input template, or both. INCON copies user input to the buffer before returning to the calling program. BufSeg Segment address of i/o buffer. KeyOff Offset address of a list of extended-key codes. Extended keys are those that have some special purpose, such as cursor and function keys. INCON reserves several extended keys for its own use (see Table 2); the others are available for use by your program. See the discussion of the xKeys flag and "Extended-Key Trapping," below. Do not include INCON's edit keys in the extended-key list. KeySeg Segment address of the extended-key list. INCON.DOC 4 Flags Flags that modify INCON's behavior, arranged as in Figure 2. The flags word is declared separately in INDEFS.H as the union of an unsigned integer and a bit-field; should you need to manipulate individual flags, you may declare a variable of type FLAGS to simplify access. In the following discussion, "set" means a one- bit flag is one; "clear" means it is zero. Debug This flag has two purposes. If set, it turns on INCON's run-time error messaging (see Message), and it makes available another debugging aid, described below. INCON attempts to recover from errors that the programmer may make in setting up an input field and supplies defaults for some parameters that are not specified. As a result, INCON may modify some of the flags and other parameters. If INCON.C, the main source file, is compiled with the constant INCON_STATS set to 1, the Debug flag also tells INCON to create a "Stat Box" that lists all parameters and flags after field initialization. The Stat Box may then be toggled on and off with the [Numpad 5] key as long as Debug remains set. See "Setting Up and Editing Input Fields" and "Error Trapping." Type This flag determines the characters that are acceptable as input. Valid characters for each type are: 0 - Alpha. ASCII characters in the range 32-255, except 127. 1 - Uppercase. Same as 0; a-z converted to A-Z. 2 - Integer. Decimal digits and optional sign only. 3 - Floating-point. Decimal digits, decimal point, and optional sign. 4 - Mixed. Template fields: Decimal digits or alpha characters only (no punctuation). Non-template fields: same as 0. INCON.DOC 5 If INCON finds a decimal point in the default string of a non-template integer field, it converts the field to signed floating-point; if it finds a leading sign character, it sets the Sign flag; if it finds any other non-digit character, including a sign in any position but the first, it truncates the string at that character. INCON returns all input types as ASCIIZ strings (null-terminated, no imbedded length); numeric conversions are left to the caller. See the discussion of the Template flag and "Setting Up and Editing Input Fields" for more on numeric types and input templates. Justify Allows input to be returned so as to fit a formatted data scheme. 0 - User input is returned as entered. 1 - User input is left-justified in a field of Width characters (see also Pad). 2 - User input is centered. 3 - User input is right-justified. This flag has no affect on floating-point and template fields. Integer fields are right-justified by default. See "Setting Up and Editing Input Fields." Strip Template fields only. If set, INCON returns user input stripped of all template delimiters. If clear, INCON returns the entire string from the input field. See Template. Among the string-handling routines mentioned above is one that restores stripped template data to their original format so that you can present existing data for editing. See "Setting Up and Editing Input Fields." Message In addition to returning an error code, INCON beeps and displays an error message when it detects any of several run-time errors. While developing a program, you may wish to enable messages; once the program is INCON.DOC 6 finished, clear this flag to suppress them (the error code is still returned). Setting Debug also turns on this flag. See "Run-Time Errors." Sign If set, the user may enter a sign character in the first position of floating-point and non-template integer fields. If INCON finds a leading sign character in the default input string passed to those field types, it sets Sign automatically. INCON prevents the user from entering a sign character in numeric templates by clearing Sign for those fields. The user may still flag input as positive or negative by using the "+" and "-" keys on the numeric keypad. See "Extended-Key Trapping" and "Setting Up and Editing Input Fields." Display Template fields only. If set, INCON displays the entire string in the i/o buffer and treats the "input slot" indicators as default input, which allows you to present for editing data that has already been formatted, as from a database. If clear, it displays only the template delimiters. See Template. Confirm If set, the user must press [Enter] to confirm input; if clear, INCON exits as soon as the input field is filled. See "Setting Up and Editing Input Fields." Delimit If set, INCON displays delimiters ("[" and "]") at each end of the input field. If part of a scrolling field is out of view, the delimiters change to "<" and ">" to indicate that the field contains data to the left or right. Delimiters are most useful for check boxes and when you don't want to use a contrasting color to set off the input field from the rest of the screen. Setting this flag increases the field width requirement by two, which may lead to an unexpected field width error. See "Run-Time Errors." xKeys If set, INCON searches the list at KeySeg:KeyOff when the user presses an extended key that is not among its reserved keys; if clear, it ignores those keys. INCON.DOC 7 If INCON finds the key in the list, it aborts the input operation and returns the extended key code to the calling routine; otherwise it produces a warning beep. See "Extended-Key Trapping." Scroll INCON does not attempt to manage line-wrap in an input field. If an alpha field is too long for one line, set this flag to allow characters to move into and out of the visible field as the user edits the input string. Place the number of characters to display in Visible (see below). INCON turns off scrolling for integer and floating- point fields, or if either of the Template or Hide flags is set. It turns on scrolling if an alpha field is wider than the space remaining on the screen row; it also turns off delimiters and sets Visible so as to carry the field to the end of the row. Hide Alpha and template fields only. For gathering secure data, such as passwords, set this flag to prevent user input from being displayed on the screen. To mark the progress of input visually, INCON writes spaces to the screen as the user makes entries into the input field; it replaces the spaces with the contents of Fill as the user makes deletions. It initially displays a string passed in the i/o buffer if Display is set, so you could put a prompt that indicates the kind of data that is required in the field itself. INCON disables scrolling, as well as all edit keys except [Backspace], [Esc], and the exit keys, when this flag is set. Extended-key trapping is not affected. Template If set, INCON treats the string passed in the i/o buffer as an input template. A template field has two types of character positions: "input slots" into which the user may enter data; and "template delimiters" to which the user has no access at all. Characters accepted as input depend upon the input Type (see above). For alpha templates, an alpha character in the i/o buffer defines an input slot; all others define delimiters. For integer templates, only digits define input slots. INCON.DOC 8 For mixed templates, alpha and digit characters define input slots, but the range of input into alpha slots is more restricted than it is for alpha templates. INCON accepts only alpha entries, no punctuation, in those slots. In addition, it converts to uppercase any entry into a slot defined by an uppercase alpha character in the template string. The following string might be passed in the i/o buffer as a template for phone numbers: (999) 999-9999 Type should specify integer input. If Display is set the input field appears as above, and INCON treats the nines as default user input. If Display is clear and Fill is defined as ASCII 46, the input field appears as (...) ...-.... In either case, the user has access only to the input slots marked by the 9s in the template string. Note that the choice of Fill character may have an impact on the operation of template fields. In the example above, one of the delimiters is a space character. If Fill is also defined as the space character, INCON will never recognize that the user has entered valid data. See "Run-Time Errors" and "Input Templates." The Strip flag affects template fields in much the same way as the "R" option in dBASE Picture Functions. If Strip is set and the user enters "1234567890" into the example field above, INCON returns "1234567890"; if Strip is clear, INCON returns "(123) 456-7890". At exit, all input slots must contain valid data; otherwise, INCON returns an error code and discards any user input. Scrolling is disabled when this flag is set. Width The maximum number of characters allowed in the input field, including the sign in numeric fields and the decimal in floating- point fields. INCON.DOC 9 Prec Alpha and integer fields: the minimum acceptable number of input characters. INCON discards user input and returns -1 if the user exits a field that contains fewer than Prec characters. Floating-point fields: the number of digits to the right of the decimal point. If the user enters fewer than Prec digits to the right of the decimal point, INCON pads the field with zeros. If the user exits an empty field, the return string is "0.", padded out with Prec zeros. Template fields: INCON sets Prec from Width, but Prec does not figure in its determination of the validity of input; the field must be filled completely for input to be valid. Visible Specifies the length of the visible portion of scrolling alpha fields. If Width is too long to fit within the confines of a window, put the number of characters to display here and set Scroll. Characters move into and out of view as the user edits or moves through the input field. If Scroll is clear, INCON sets Visible from Width. Attr Input field colors, specified as an IRBG attribute byte. If 0, INCON reverses the current screen attribute and preserves the intensity bit. If the foreground and base background colors in Attr are the same, INCON sets the intensity bit. Therefore, you normally can't use Attr to get hidden input (see Hide), though you can fool INCON by turning off the blink attribute, which makes 16 background colors available. If you want to get your users' attention, or just annoy the hell out of them, you can set up a blinking input field. Fill The character INCON uses to fill unoccupied portions of the input field, as a visual guide to the user. You may specify any value (0-255) here, but if Fill is less than 32 INCON uses the space character. Pad The character INCON uses to pad the i/o buffer when justified input does not fill it completely (see Justify, above). The range of values is the same as for Fill. INCON.DOC 10 If an integer field will be converted to a number, Pad must be acceptable to the conversion routine. INCON uses leading spaces and trailing zeroes (ASCII 48) to pad floating-point fields, regardless of the character specified here. See "Setting Up and Editing Input Fields." Setting up the Message Block and Calling INCON Figure 3 shows the steps reuired to set up a message block and call INCON. As mentioned above, you may treat the message block as either a structure or an array of unsigned integers. A message block is defined in Figure 3a and initialized as an array in Figure 3b. The value assigned to the flags in Figure 3b is comprised of several constants defined in INDEFS.H. The flags tell INCON that nblock expects integer input and to right-justify user input in the i/o buffer for return to the caller (which INCON would do by default, since nblock defines an integer field). INCON displays as default input any string that occupies the i/o buffer at entry. The user must press [Enter] to confirm input, and, since extended-key trapping is enabled, the user may cancel input by pressing a key in the extended- key list. INDEFS.H defines constants for setting, shifting, and masking individual flags. The constants assigned in Figure 3b to Width, Prec, and so on are defined in the INCON demonstration program, INDEMO.C; their specific values are not important for purposes of illustration. A far pointer to the message block is defined in Figure 3c and passed to INCON in Figure 3d. INCON is declared as a Pascal type, so its name may appear in mixed case, as shown, or in uppercase. Extended-Key Trapping To give users a means of communicating special requests to your program, you may define a list of extended-key codes for INCON to search when extended-key trapping is enabled (the xKeys flag is set). INCON treats the list as a C string, so it must end with a null byte. If xKeys is set, INCON cancels input when the user presses an extended key in the list. It discards any user input and returns the extended code to the caller. Extended-key trapping offers a more powerful means of aborting input than a simple "cancel" key. You may, for example, define keys that allow your program to respond immediately to user requests for services such as navigating a menu or obtaining help. INCON.DOC 11 The following example defines a list of unshifted function keys, along with [Tab] and [Shift+Tab]. Note the 0 byte that terminates the list. static unsigned char xKeyList[] = {9, 15, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 0}; To disable extended-key trapping you may define the list as a null string (a single zero byte), pass a null pointer in xKeyList (zeros in KeyOff and KeySeg), or clear the xKeys flag. Though the unshifted [Tab] is not an extended key, INCON treats it as such if you include its ASCII code in the list. Since ASCII 9 has no analogue among extended codes, it does not mask any of them. INCON returns extended codes in the LOW byte of the return value. Since the only positive non-zero returns from INCON represent either [Esc], [Tab], [Numpad +], [Numpad -], or an extended key, all are readily identifiable. Special Exit Keys INCON gives special handling to two extended keys, [Numpad +] and [Numpad -]. In alpha fields, they map to the regular [+] and [-] keys. In mixed templates, they are ignored. In integer templates, they act as special exit keys. In floating-point and non-template integer fields, however, INCON treats them as either regular ASCII keys or special exit keys, depending upon the condition of the Sign flag and the position of the cursor. If Sign is set AND the cursor is at the beginning of the field, they act as alternates to the upper row [+] and [-] keys. If Sign is clear OR the cursor is NOT at the beginning of the field, INCON treats them as exit keys and returns their scan codes. That can be useful when you have set up a numeric field of a particular size and don't want to dedicate a position to the sign. Your program can still determine whether the entered quantity is positive or negative. None of the conditions set by Template or Prec is relaxed. All input slots in an integer template must contain valid data; non- template integer fields must receive at least Prec digits of input. INCON returns -1, not the extended codes, if the user exits without having met those conditions. [Numpad +] and [Numpad -] need not be included in xKeyList; INCON handles them internally, as summarized in Table 1. INCON.DOC 12 Setting Up and Editing Input Fields This version of INCON operates in insert mode in alpha fields and in overstrike mode in numeric fields and templates. No provision for switching modes is supported. Width and Visible settings may allow the input field to extend beyond the boundaries of a window defined by the calling program. The caller must manage INCON's parameters to conform to the dimensions of any window that hosts an input field. INCON makes its own modest use of windowing to display its "Stat Box" if you've set Debug and are using a version of the library compiled with the constant INCON_STATS set to 1 (see the Debug flag and "Error Trapping"). The Stat Box is toggled with the [Numpad 5] key; while it is displayed, all other keys are ignored. INCON saves and restores the screen under the Stat Box. INCON reserves several keys, listed in Table 2, for editing input fields. If Hide is set, all keys in Table 2 are disabled except for [Backspace], [Esc], [Numpad +], [Numpad -], and [Enter]. The Hide flag does not affect extended-key trapping. INCON's initial placement of the cursor in the input field depends upon the field type. The cursor appears in integer and scrolling fields at the start of the field, in non-scrolling alpha fields at the end of the default input string, in template fields at the first input slot, and in floating-point fields at the first character of the default input string. If the user hits a key that is not appropriate to the field type or attempts to move the cursor outside the boundaries of the input field, INCON issues a warning beep. The same is true when the cursor is not at the end of an alpha field that is filled to capacity and the user attempts to enter more characters into the field, a situation that is discussed further below. If the first entry in a field is a valid character, INCON clears the default input string and places the character at the beginning of the field, or in the first input slot. If, however, the first entry is any key that causes the cursor to move, INCON places subsequent characters at the cursor position; the default string is not cleared. In short, fields work basically as follows: to accept the default input string, press [Enter]; to edit the string, use the edit keys; to replace the string, just start typing. Beware of a situation with alpha fields in which INCON appears to freeze. Suppose you've set up a CONFIRMED field and a default input string that fills it. That may result either from your own settings or, without your knowing it, if you've left it to INCON to set the field width from the length of the default string. If the first entry in the field moves the cursor out of its initial position, INCON will refuse to accept any valid entries because the field is already filled INCON.DOC 13 to capacity. That situation is most likely to arise in a scrolling field in which the end of the string is out of view, and the cursor is placed initially at the start of the field. You can tell INCON hasn't gone witless because, with each keypress, you'll hear a warning beep that indicates the field is filled. To make entries into the field you must clear it or delete a few characters. By contrast, given a similar UNCONFIRMED field, INCON will exit immediately with the first entry of any kind. In neither case is INCON behaving inconsistently, but those situations can take you by surprise. It is best not to leave too many decisions to INCON; set the parameters you want so that INCON doesn't have to. And be sure to give yourself plenty of room; overly long alpha fields can be scrolled. You may specify that user input from non-template alpha and integer fields be returned to your program either left-justified, right-justified, or centered. Integer fields are right-justified by default, but you can override that by setting Justify to Left or Centered. INCON takes the total length of the returned string from Width, and the character that fills out the string from Pad. The justification routines and a number of other string-handling routines are public, so you may call them directly from your own programs. They also are available separately by linking STRINGZ.OBJ to programs that don't require INCON's services. Prototypes and more information are available in the header file STRINGZ.H. The justification routines are capable of returning a string of characters, much like BASIC's STRING$() function. Pass a pointer to a destination buffer, another to a null source string, a length, and a pad character. The destination buffer must be at least as long as the length you specify, plus an additional byte for the final null. Experiment with this feature in the demo program by setting up an alpha field with no default input string, non-zero Width, zero Prec, and a Pad character. Then select different justification settings and hit [Enter] in the empty input field. If the string returned from an integer field is to be converted to a number, Pad should be the space character (ASCII 32). Padding with "0" (ASCII 48) will not work with a signed integer field and the default right justification, since INCON places the sign adjacent to the entered digits. The returned string may be something such as "0000-123", which the standard numeric conversion routines will translate as 0. Input Templates INCON uses the character in Fill to mark empty input slots in the template. Since all input slots in a template must contain valid data at exit, the presence of a Fill character in the input field is an input error. Therefore, a template cannot be used to obtain input that includes the Fill character. INCON.DOC 14 For the same reason, the Fill character must not be the same as any of the template delimiters. The template "(999) 999-9999" includes a space as a delimiter; if Fill is the space, either by choice or by default, INCON will issue a run-time error. The small bullet (ASCII 250) and the phantom space (ASCII 255) are generally good choices for Fill. A handy feature of integer templates is that you can imbed prompts within them. If, for example, you are using fixed-point math to deal with currency, you might set up a STRIPPED integer template such as Amount: $ 00000.00 Users could make entries in familiar dollars and cents, but your program would receive the entry in cents. Note that quantities of less than $10,000 require leading zeros in the entry because, being a template, the field must be filled completely. The user may end input with [Numpad +] or [Numpad -], allowing your program to determine whether Amount is positive or negative. INCON will accept the characters that mark input slots in the template string as valid input if Display is set. If you want to display a default string, you may need to select some out-of-range "flag" value so that your program recognizes when the user has merely pressed [Enter] in the field. If, given the example above, an amount of 0 were invalid, your program could display an error message if the user pressed [Enter] on the default input string. If, on the other hand, valid amounts ranged from plus-or-minus 0 to 50,000 you could substitute nines for the zeros in the default input string. To obtain the entire range of values, from 0 to 99,999.99, you'd have to clear the Display flag. The initial input field would then be filled with Fill characters, triggering an input error if the user just pressed [Enter] on the empty field. Use mixed templates to obtain patterned data that consists of mixed alpha and numeric data. Input into mixed templates is more restricted than into other types. Digits in the template string map input slots that accept only numeric input. Alpha input slots accept only alpha entries; no punctuation is allowed. In addition, case is significant in alpha input slots. For example, X-999-999-999-999 defines a template that accepts only alpha characters in the first input slot and only digits in the remaining slots; INCON converts an entry in the first slot to uppercase. (That is not an artificial example; Michigan drivers' licenses carry a serial number of that form. Apparently, someone foresaw the potential for substantial growth in the State's population. Among the public string-handling routines mentioned above is a fairly simple-minded routine that restores a stripped template to its original format. You pass it a pointer to a template string, a INCON.DOC 15 pointer to the data string you want to format, and a flag character that tells it where the data goes in the template. For example, if the previous example were used in a database application, you might want to store input in stripped form in order to save space. To later present the data in its original format for editing, you could pass a template such as x-xxx-xxx-xxx-xxx to the restore routine, TemplStr(), along with the data string and the flag character ("x" in this case). TemplStr() would plug characters from the data string into the template string at the places marked by the flag character. Notice that the format of the template string is not as strict as it is for INCON templates. The only requirement is that the flag character not be the same as any of the template delimiters. INCON offers no dedicated date type, but you could set up templates to get dates in any of several forms. For example, any of the following templates would serve: "99 Xxx 99" "XXX 99, 9999" "99/99/99" The first two are mixed templates for getting dates with the standard three-character month abbreviations; the third may be integer or mixed. A template is not suited to getting expanded month names because they vary in length. If you need the date in a form that allows you to do calculations with it, such as verifying leap years and so on, you could set up adjacent fields to get the month, date, and year individually, or use the string-handling routines to parse the return from a template such as one of those above. Editing template fields differs from editing other fields in several ways. First, the cursor cannot be moved into positions that are occupied by template delimiters. Second, a "word" in a template field consists of one or more input slots bounded by template delimiters, or by the ends of the field. Third, INCON does not move characters across word boundaries during deletes. Floating-point Fields INCON sets the Display and Confirm flags in floating-point fields. It calculates the position of the decimal point in the field from the values of Width and Prec. If both are 0, INCON bases its calculations on the length of the default input string and the position of the decimal point. If either is non-zero, it takes precedence; INCON may not succeed in creating an input field in that case. To find out exactly how INCON handles missing parameters, experiment with the demo program. If you pass a number (converted to an ASCIIZ string) in the i/o buffer, INCON displays it as default input. INCON fixes a default string that does not conform to the format of the input field by INCON.DOC 16 copying digits from the i/o buffer into the field until it finds the decimal in either the default string or the field. In the first case, it adjusts the field to close any gaps to the left of the decimal; in the second, it discards uncopied digits to the left of the decimal in the default string. It then copies digits to the right of the decimal until it either reaches the end of the default string or fills the field. If INCON finds more than one sign character to the left of the decimal in the i/o buffer, it uses the last one and discards any characters found previous to that. It also discards sign characters to the right of the decimal, as well as all non-digit characters. For example, suppose that you have set up a field of Width 10 and Prec 4. If you pass a default string of "123.456789", INCON puts " 123.4567" into the input field. It moves the integer portion of the string adjacent to the decimal point and discards extra digits in the decimal portion, with a resulting loss of precision. If the default string is "123456.789", it puts "12345.789 " into the input field and discards the extra digit in the integer portion of the string, with a disastrous impact on magnitude. To avoid such a calamity, be sure that the input field is adequate to hold the largest number likely to be encountered in your data. INCON insists on showing at least one integer position in the input field. Given Width 10, Prec 9, and a default string of ".123456789", INCON would put "0.12345678" (or "+/-.12345678" if the default input string leads off with a sign) into the input field. It would reduce Prec to 8 in order to accommodate the integer digit. In order to retain maximum flexibility in editing floating-point fields, all of the edit keys are active. That means the user can enter a digit, cursor over a place or two, enter another digit, and so on. Though unlikely, such a clumsy sequence is nonetheless possible. The gaps thus introduced into the input field are eliminated when the user exits the field or whenever the cursor passes over the decimal point. In addition, when the cursor passes over the decimal from left to right, the integer digits are moved adjacent to the decimal point; if it passes back from right to left, the field is padded out with zeros. If the cursor moves left into the position occupied by the sign (or the first digit if no sign is present), all integer digits are moved back to the beginning of the input field. If the first entry in the input field is a digit or sign (in signed fields only), INCON clears the field and places the entry in the first position. If the user enters a decimal point before having filled the integer portion of the field, integer digits are moved adjacent to the decimal point and input continues with decimal digits; integer digits that already may have been in place, from the cursor to the decimal point, are discarded. A decimal point is accepted only when the cursor is in the integer portion of the field; any time one is entered legally, the decimal portion of the field is cleared. INCON.DOC 17 Here's a sequence of entries and the resulting condition of the input field, given Width 10, Prec 4, Fill character 42, and default input string "123.4567" (the parenthesized character in the third column marks the position of the cursor): Entry Display Cursor ------- ----------- ------------ 123.4567 (1)23.4567 9 9****.**** 9(*)***.**** 3 93***.**** 93(*)**.**** . 93.**** 93.(*)*** 2 93.2*** 93.2(*)** [Right] 93.2*** 93.2*(*)* 5 93.2*5* 93.2*5(*) [Home] 93***.2500 (9)3***.2500 8 83***.2500 8(3)***.2500 . 8.**** 8.(*)*** [Enter] 8.0000 A sign character is accepted only if the Sign flag is set and the cursor is at the beginning of the field. In that case, the sign may be entered using either the upper row keys or the Numpad keys. If Sign is clear or the cursor is not at the beginning of the field, the upper row keys are rejected and the Numpad versions exit the field. If INCON finds a decimal point in the default input string passed to a non-template integer field, it converts the field to signed floating-point. Initialization then proceeds as above. Scrolling Fields Only non-hidden alpha fields can be scrolled. INCON turns off or ignores the Scroll flag in numeric, template, and hidden fields, so field length is limited to the width of the Mode 3 screen. Most edit keys are disabled in hidden fields, so they can't be scrolled to begin with. During word deletes to the left, [Ctrl+L] ceases to function when the cursor reaches the left end of the visible field. That is a deliberate handicap, intended to prevent the user from accidently deleting characters that are out of view. During word deletes to the right, INCON moves characters beyond those deleted to the cursor position, so no such precaution is taken. Return Codes INCON returns a short integer that indicates the status of the input operation. Error returns have the high bit set; extended-key codes come back in the low byte of the return value. Return values and their meanings are listed below. INCON.DOC 18 0 Input accepted; no error. INCON copies user input to the i/o buffer for return to the caller. -1 Input error. Alpha and integer fields: the user exited the field but has entered fewer than Prec characters. Template fields: the user exited the field but left at least one input slot vacant. 27 Input cancelled. The user pressed [Esc] to abort input. Pressing [Esc] in an input field that contains data clears the field and input may continue. Pressing [Esc] in an empty field aborts input and INCON returns to the caller. 74 Input accepted; no error. 78 The user pressed [Numpad -] or [Numpad +] to end input. These returns are subject to special conditions. See "Special Exit Keys," above. ## Other extended-key codes. The user pressed a key in the extended-key list to abort input. INCON ignores keys in the list unless the xKeys flag is set. In most cases, INCON does not alter the default input string on user error or abort. It does, however, eliminate leading and trailing spaces and control codes during initialization of floating-point and non-template integer fields, so default strings for those fields are always subject to modification. Note that there is no error return for type float. If the user exits an empty input field, the returned string is made up of "0." padded out with Prec zeros; the initial contents of the i/o buffer are lost. The only time the default input string comes back unaltered in a floating-point field is when the user presses [Esc] to cancel input. Before returning to the calling routine, INCON restores the cursor to its position at entry. It needn't be reset if an input error requires that INCON be recalled immediately. INCON.DOC 19 Run-Time Errors When INCON encounters a run-time error it beeps, prints a message, and waits for you to press a key; it then returns an error code to the calling routine. The returned code is one of the error numbers listed below, minus 32768 (the high bit is set). INCON checks for run-time errors in the order they are listed and flags the first it finds, so there may be more than one. Correct the one identified in the message; INCON will flag a higher-numbered error at the next run. Run-time error messages have the form INCON error #: Message text. Press any key... where # and "Message text" are taken from the list below. The error message appears in a bar of the color in Attr that extends across the entire screen at the row occupied by the input field; you may suppress it by clearing the Message flag (but see also the Debug flag, above). Error # Message -------- -------------------------------------------------- 1 "Invalid field precision" Prec is greater than Width. This error applies to fields of any type. 2 "Invalid field width or scroll visible length" Width or Visible is zero, or greater than the number of screen columns remaining on the line. This error may occur unexpectedly when Delimit is set, since the number of columns required for the input field is increased by two. INCON will set Visible itself if you don't initialize it, taking account of field length and position, and the space remaining on the screen row. If possible, it sets Visible to the same value as Width, which simplifies string indexing. If you specifically set Visible to an incorrect value for a scrolling alpha field, however, INCON will issue this error, rather than attempting to override your setting. 3 "Default input string too long" The input string passed from the caller is longer than Width characters. 4 "Type float; precision is invalid" Float precision is 0 or greater than Width. INCON.DOC 20 5 "Type float; no room for decimal point" Width and Prec are equal, leaving no room for the decimal point. This error may occur unexpectedly when INCON forces an integer field to type float (see the discussion of the Type flag, above). 6 "Fill character appears in template" At least one template delimiter is the same as the Fill character. 7 "Invalid template" No template pattern was supplied in the i/o buffer, or the one supplied comprises only delimiters. In an alpha template only alpha characters define input slots; in an integer template only digits; in a mixed template, either digits or alpha characters. Spaces and other punctuation define delimiters. 8 "Insufficient memory for internal buffers" INCON was unable to allocate memory for its working buffers. 9 "Input/output buffer pointer is NULL" The i/o buffer must point to a valid program data area. Error Trapping INCON attempts to trap several potential run-time errors. Two of them, forcing signed input and converting field type to floating- point, were mentioned in discussing the Type flag. Another arises when Width is greater than the remaining length of the screen row and you forget to set Scroll; INCON then sets the flag, sets Visible to carry the field to the end of the row, and clears Delimit. On the other hand, should you fail to define any value at all for Width, INCON sets it to the length of the default input string; if that, too, is zero, INCON gives up and issues a run-time error. INCON cannot check the length of the i/o buffer against Width. It is the responsibility of the calling routine to insure that the buffer is large enough to hold the requested number of characters, plus the final null byte. You can use INCON's error trapping to simplify parameter-setting in your programs. For example, you needn't set Width, Prec, or Visible for a template field, since INCON takes all of those parameters from the length of the template. In most fields, INCON.DOC 21 Attribute, Fill, and Pad can be 0; INCON sets Attribute to inverse video, and Fill and Pad to the ASCII space (keep in mind the restrictions on Fill in templates, however). INCON maintains private copies of the contents of the message block; changes it makes to the parameters you've defined are made to its copies. If, during debugging, you want to see just what INCON does with the contents of the message block, you can request that it show all parameters and flags after modification, if any, by field initialization. Immediately after initialization, INCON creates a "Stat Box" window at the bottom of the screen, in which it displays the altered flags and parameters (see Figure 4). The Stat Box will flash on and off as INCON prints the data to the screen and saves it. If the Debug flag is set, you may then use [Numpad 5] to toggle the Stat Box on and off. INCON saves and restores the contents of the screen under the Stat Box. Note that you must have compiled INCON.C with the constant INCON_STATS set to a non-zero value for the Stat Box routine to be included in the object file. If INCON_STATS is 0 when you compile INCON.C, the Stat Box routine and all references to it disappear. In that case, the only effect of the Debug flag is to turn on the Message flag. The demonstration program, INDEMO.EXE, prints its own Stat Box, which shows the flags and parameters as you've defined them, prior to calling INCON. Until you exit the newly-created input field, you can toggle INCON's Stat Box on and off to compare your settings with the changes, if any, INCON has made. See the file INDEMO.DOC for more details. INCON.DOC 22 Figure 1. INCON Message Block. Offset Low Byte | High Byte +-----------------------+ 0 | BufOff | |-----------------------| 1 | BufSeg | |-----------------------| 2 | KeyOff | |-----------------------| 3 | KeySeg | |-----------------------| 4 | Flags | |-----------+-----------| 5 | Width | Prec | |-----------+-----------| 6 | Visible | Attr | |-----------+-----------| 7 | Fill | Pad | +-----------+-----------+ Figure 2. INCON Flags. Bit: 15 14 13 12 11 10 9 8 | \ | / \ / | | Debug Type Justify Strip Message ------- ------------- ---------- ------- --------- 0 = No 0 = Alpha 0 = None 0 = No 0 = No 1 = Yes 1 = Uppercase 1 = Left 1 = Yes 1 = Yes 2 = Integer 2 = Center 3 = Float 3 = Right 4 = Mixed Bit: 7 6 5 4 3 2 1 0 | | | | | | | | Sign Display Confirm Delimit xKeys Scroll Hide Template ---- ------- ------- ------- ----- -------- ---- -------- For all: 0 = No / 1 = Yes INCON.DOC 23 Figure 3. The INCON Interface. MBLOCK nblock; a) Declaring a message block. nblock.iblock[0] = FP_OFF( ioBuffer ); nblock.iblock[1] = FP_SEG( ioBuffer ); nblock.iblock[2] = FP_OFF( xKeyList ); nblock.iblock[3] = FP_SEG( xKeyList ); nblock.iblock[4] = FLAG_INTGR | FLAG_RJUST | FLAG_DISPLAY | FLAG_CONFIRM | FLAG_XKEYS ; nblock.iblock[5] = WIDTH | (PREC << 8); nblock.iblock[6] = VISIBLE | (ATTR << 8); nblock.iblock[7] = FILL | (PAD << 8); b) Initializing the message block as an integer array. MBLOCK far * block_ptr = &nblock; c) Defining the message block pointer. short incon_ret = InCon( block_ptr ); d) Calling INCON. INCON.DOC 24 Figure 4. The INCON Stat Box. Parameters are shown in hexidecimal (X); flags in binary (B). ╔════════════════════════════════════════════════════════════════════════════╗ ║ INCON 3.1 Copyright (c) 1993-94, Richard Zigler ║ ║ ioBuf segment:offset = XXXX:XXXX xKeyList segment:offset = XXXX:XXXX ║ ║ Width: XX Prec: XX Visible: XX Attr: XX Fill: XX Pad: XX ║ ║ Flags: B BBB BB B B B B B B B B B B Use [Numpad 5] to toggle Stat Box ║ ╚════════════════════════════════════════════════════════════════════════════╝ Table 1. INCON's Handling of [Numpad +] and [Numpad -] (X means "don't care"). Field Sign Template Type Flag Flag Action ------- ------ -------- ------------------------- Alpha X X Map to upper row +/-. Integer 0 0 Exit, return scan code. Integer 1 0 Sign in first position; else exit, return scan. Integer X 1 Exit, return scan code. Float 1 X Sign in first position; else exit, return scan. Float 0 X Exit, return scan code. Mixed X 1 Illegal; audible warning. INCON.DOC 25 Table 2. INCON Edit Keys. Key(s) Normal Field Template Field ---------- ---------------------- ---------------------- [Home] Move cursor to start Move cursor to first of input string. input slot. [End] Move cursor to end Move cursor to last of input string. input slot. [Left] Move cursor to Move cursor to previous character. previous input slot. [Right] Move cursor to Move cursor to next character. next input slot. [Ctrl+Home] Clear input field from Clear input slots from cursor to beginning. cursor to beginning. [Ctrl+End] Clear input field Clear input slots from cursor to end. from cursor to end. [Ctrl+Left] Move cursor to Move cursor to previous previous word. input group. [Ctrl+Right] Move cursor to Move cursor to next next word. input group. [Ctrl+L] Delete word left. Delete group left. [Ctrl+R] Delete word right. Delete group right. [Backspace] Delete character Clear input slot left. left. [Del] Delete character Clear input slot at cursor. at cursor. [Esc] Clear entire input Clear all input field. slots. [Esc]+[Esc] Cancel input. Cancel input. [Enter] End input. End input. [Keypad +] Sign or special exit. Special exit. [Keypad -] Sign or special exit. Special exit. INCON.DOC 26